home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Tools / Languages / MacGofer 0.22d / MacGofer Sources / Mac Notes < prev    next >
Encoding:
Text File  |  1994-05-05  |  6.6 KB  |  187 lines  |  [TEXT/MPS ]
  1. Notes on the Macintosh Port of Gofer, Version 0.22d
  2. ===================================================
  3.     
  4. Kevin Hammond, Glasgow University, 5th May 1994
  5.  
  6.  
  7. Copyright
  8. ---------
  9.  
  10. These sources are Copyright © 1991-1994. The copyright to portions of the 
  11. source code is owned by
  12.  
  13.     Mark Jones,    Yale University
  14.     Kevin Hammond,    Glasgow University
  15.     Humayan Lari,    University of North Carolina
  16.     Manuel Veloso,    Allston, MA
  17.  
  18. and    Glasgow University on behalf of Matthew Smith, Alex Stewart 
  19.     and Desmond Yip
  20.  
  21.  
  22. Licence
  23. -------
  24.  
  25. Please see the file "goferite.h" for the general licence and conditions
  26. of use of this source code.
  27.  
  28.  
  29. The Sources
  30. -----------
  31.  
  32. The files in this directory are the sources for MacGofer and for the
  33. MPW tool version of Gofer.  I recommend you use the standalone version,
  34. the tool can be rather frustrating!  To compile these sources you will
  35. need:
  36.  
  37.     MPW shell, Assembler and C compiler version 3.2 or later
  38.     
  39. Think C will not do!  I tried, but the lack of intra-file segmenting
  40. meant that kind.c/preds.c/type.c would need to be entirely rewritten.
  41. Everything else should compile OK, but I haven't checked this recently.
  42.  
  43. Mac-specific source files are mac_*; other source files are derived from
  44. the Gofer 2.28b distribution.  There are a few special files.
  45.  
  46.     MacGofer.rez        contains a Rez template for the MacGofer resources.
  47.                 Can be compiled using rez to generate MacGofer.r
  48.             
  49.     MacGofer.r        contains the resources for MacGofer.  Edit this
  50.                 using ResEdit
  51.             
  52.     MacGofer.make        is the makefile.  Use the MPW build command for
  53.                 MacGofer to build the application, or rename
  54.                 it to Gofer.make and build Gofer to make the
  55.                 MPW tool.
  56.             
  57.     mac.h            is the main header file for MacGofer.
  58.     
  59.     mac_humayan_utils.[ch]    are some utilities written by Humayan Lari
  60.                 to make integrating with the toolbox easier.
  61.     
  62.     mac_trap.a        is the "ccall" implementation using self-modifying
  63.                 assembly code.
  64.                 
  65.     mac_SFMultiGet.c    is source code for a multi-file standard file
  66.                 dialog, used in Load File…  This was borrowed
  67.                 from the net.
  68.                 
  69.     mac_StrInit.c        is the code for initialising strings from the
  70.                 string resources held in MacGofer.
  71.  
  72. The other sources should have fairly obvious names.  Note that parser.y has
  73. been changed so that buildTuple is exported.  This proved to be useful in
  74. prims.c.
  75.  
  76.  
  77. Compiling MacGofer
  78. ------------------
  79.  
  80. You should be able to build MacGofer with a standard MPW setup.  The
  81. build directory needs about 3M on my system, including 700K for the
  82. .SYM file.  If you don't expect to spend time in the debugger, you
  83. should set SYM = -sym off in the makefile -- this will significantly
  84. speed up compilation and linking, which will otherwise take around
  85. ~30 minutes for a complete rebuild on my SE/30.
  86.  
  87.  
  88. Using MPW Tool Versions
  89. -----------------------
  90.  
  91. The files Gofc.make and Gofer.make are provided so that MPW Tool versions 
  92. of the Gofer compiler and interpreter can be built.  MacGofer does not 
  93. provide the compiler facilities of gofc.
  94.  
  95. To run the compiler/interpreter, you may find you need to change the
  96. default memory settings (-mx flags).  With a 2M partition for the MPW 
  97. shell, I found I needed to use -ma8000 if I was to avoid the program
  98. memory exhausted message.  Larger partitions may be  necessary in order 
  99. to compile or run large programs.
  100.  
  101.  
  102. Changes to the Standard Sources
  103. -------------------------------
  104.  
  105. By default, MacGofer is compiled with simple tracing on, and with the
  106. special monad syntax in Gofer 2.28, but without the experimental
  107. lambdavar extensions.  It uses 32-bit Ints and Floats.
  108.  
  109. There are many places where changes have been made in order to build
  110. an interface around the Gofer interpreter.  Obviously, the command
  111. interface has needed to be changed, but there are also some other
  112. important but less obvious differences:
  113.  
  114. o    Explicit recursion stack overflow checking is performed.
  115.     Without this, MacGofer would crash inexplicably during deep
  116.     calls to the typechecker etc.  You can increase the stack by
  117.     changing a STR resource.
  118.     
  119. o    Because Gofer garbage collects off the C stack, the program is 
  120.     VERY sensitive to stack alignment.  IF YOU CHANGE ANYTHING WHICH
  121.     CALLS A GOFER ROUTINE WHICH MIGHT GARBAGE COLLECT, YOU MUST MAKE
  122.     SURE THAT THE STACK FRAME IS INCREMENTED BY A LONGWORD NUMBER OF
  123.     BYTES.  It is not sufficient to do this by source inspection --
  124.     the MPW C compiler is clever enough to reuse stack locations, and
  125.     to registerise local variables when possible (this could actually
  126.     cause problems for the garbage collector too!).  Use the dumpobj
  127.     command from MPW to inspect the object code, and look for LINK
  128.     instructions.  Float and Bool values are especially problematic.
  129.     The files affected are machdep.c, prims.c, input.c and machine.c
  130.     
  131. o    For a similar reason, the Float primitive code has had to be written
  132.     VERY carefully.  Follow the rules given in machine.c when changing
  133.     this!
  134.     
  135. o    Standard I/O routines have been rewritten to read from/write to the 
  136.     worksheet when appropriate (see mac_io.c).  Note that this version 
  137.     of printf is incomplete, and may fail if a char rather than an int 
  138.     is printed using %c for example.
  139.  
  140. o    MacGofer buffers keyboard events internally, so that they can be
  141.     used either by getchar, or by a call to getNextEvent in a program
  142.     which interfaces with the toolbox (see mac_io.c).
  143.     
  144. o    Gofer now checks for EOF at places other than end-of-line.  On the
  145.     Mac, EOF can occur anywhere!
  146.     
  147. o    Fatal Gofer errors don't bomb out of the application, but return
  148.     you to the prompt.
  149.     
  150. o    Heap sizes etc. are not compiled in, but can be changed by the user.
  151.     Sizes have to be fixed across a single session, however.
  152.     
  153. o    The full 8-bit Mac character set is supported in the standard
  154.     fonts, by replacing ctype by a special version.
  155.     
  156. o    You can change the Prelude.  Users kept complaining about needing
  157.     to exit and restart with Mark's design.
  158.  
  159. o    Scoping has been changed for some local functions, e.g. buildTuple
  160.     in parser.y
  161.  
  162. o    sinh, asinh, etc. primitives have been defined.  There didn't
  163.     seem a good reason to exclude these.
  164.     
  165. o    Gofer supports Hex constants of the form 0x... plus some primitive
  166.     bit-manipulating functions.
  167.  
  168.  
  169. Making Changes etc.
  170. -------------------
  171.  
  172. Please contact me (Kevin Hammond: kh@dcs.glasgow.ac.uk) if you wish to 
  173. incorporate your changes into the main distribution, or wish to obtain 
  174. permission to distribute MacGofer in any other fashion.
  175.  
  176. The latest version of the source and binaries can be obtained from
  177.  
  178.     ftp.dcs.glasgow.ac.uk [130.209.240.50]
  179. in    pub/haskell/gofer/macgofer
  180.  
  181. Note that MacGofer is supported entirely from my (very) limited free time.
  182. While I will try to fix serious bugs and respond to email as rapidly 
  183. as possible, it is not reasonable for you to expect commercial levels 
  184. of support!
  185.  
  186. Kevin
  187.